csstree-validator

CSSTree Validator

CSS validator built on CSSTree

Usage

> npm install csstree-validator

Validate CSS string or CSSTree's AST:

import { validate } from 'csstree-validator';
// Commonjs:
// const { validate } = require('csstree-validator');

const filename = 'demo/example.css';
const css = '.class { pading: 10px; border: 1px super red }';

console.log(validate(css, filename));
// [
//   SyntaxError [SyntaxReferenceError]: Unknown property `pading` {
//     reference: 'pading',
//     property: 'pading',
//     offset: 9,
//     line: 1,
//     column: 10
//   },
//   SyntaxError [SyntaxMatchError]: Mismatch {
//     message: 'Invalid value for `border` property',
//     rawMessage: 'Mismatch',
//     syntax: '<line-width> || <line-style> || <color>',
//     css: '1px super red',
//     mismatchOffset: 4,
//     mismatchLength: 5,
//     offset: 35,
//     line: 1,
//     column: 36,
//     loc: { source: 'demo/example.css', start: [Object], end: [Object] },
//     property: 'border',
//     details: 'Mismatch\n' +
//       '  syntax: <line-width> || <line-style> || <color>\n' +
//       '   value: 1px super red\n' +
//       '  ------------^'
//   }
// ]

Another option is to use helpers to validate a file or a directory and one of buildin reporters:

import { validateFile, reporters } from 'csstree-validator';

console.log(reporters.checkstyle(validateFile('./path/to/style.css')));

Validate methods

• validate(css, filename)
• validateAtrule(node)
• validateAtrulePrelude(atrule, prelude, preludeLoc)
• validateAtruleDescriptor(atrule, descriptor, value, descriptorLoc)
• validateDeclaration(property, value, valueLoc)
• validateRule(node)

Helpers

All helper function return an object where key is a path to a file and value is an array of errors. The result object is iterable (has Symbol.iterator) and can be used with for ... of or ... operator.

const result = validateFile('path/to/file.css');

for (const [filename, errors] of result) {
  // ...
}

• validateString(css, filename)
• validateDictionary(dictionary)
• validateFile(filename)
• validatePath(searchPath, filter)
• validatePathList(pathList, filter)

Reporters:

• json
• console
• checkstyle
• gnu

Using in a browser

Available bundles to use in a browser:

• dist/csstree-validator.js – minified IIFE with csstreeValidator as a global

<script src="node_modules/csstree-validator/dist/csstree-validator.js"></script>
<script>
  const errors = csstreeValidator.validate('.some { css: source }');
</script>

• dist/csstree-validator.esm.js – minified ES module

<script type="module">
  import { validate } from "csstree-validator/dist/csstree-validator.esm.js";

  const errors = validate('.some { css: source }');
</script>

One of CDN services like unpkg or jsDelivr can be used. By default (for short path) a ESM version is exposing. For IIFE version a full path to a bundle should be specified:

<!-- ESM -->
<script type="module">
  import * as csstreeValidator from 'https://cdn.jsdelivr.net/npm/csstree-validator';
  import * as csstreeValidator from 'https://unpkg.com/csstree-validator';
</script>

<!-- IIFE with csstreeValidator as a global -->
<script src="https://cdn.jsdelivr.net/npm/csstree-validator/dist/csstree-validator.js"></script>
<script src="https://unpkg.com/csstree-validator/dist/csstree-validator.js"></script>

NOTE: Helpers and reporters are not available for browser's version.

CLI (terminal command)

> npm install -g csstree-validator
> csstree-validator /path/to/style.css

> csstree-validator -h
Usage:

    csstree-validate [fileOrDir] [options]

Options:

    -h, --help                     Output usage information
    -r, --reporter <nameOrFile>    Output formatter: console (default), checkstyle, json, gnu
                                   or <path to a module>
    -v, --version                  Output version

Custom reporters

In addition to predefined (buildin) reporters, you can specify the path to a module or a package with a custom reporter. Such module should export a single function which takes the validation result object and returns a string:

export default function(result) {
  const output = '';

  for (const [filename, errors] of result) {
    // ...
  }

  return output;
}

// For CommonJS:
// module.exports = function(result) { ... }

The specifier for a custom reporter might be:

• ESM module – a full path to a file with .js extension
• CommonJS module – a full path to a file with .cjs extension
• ESM package – a package name or a full path to package's module (i.e. package/lib/index.js)
• CommonJS package – a package name or a path to package's module (i.e. package/lib/index.js, package/lib/index or package/lib)
• Dual package – a package name or a full path to package's module

The resolution algorithm is testing reporter option value in the following order:

• If a value is a path to a file (a base dir for relative paths is process.cwd()), then use it a module
• If a value is a path to a package module (a base dir for node_modules is process.cwd()), then use package's module
• Otherwise the value should be a name of one of predifined reporter, or an error will be raised

Ready to use

Plugins that are using csstree-validator:

• Sublime plugin
• VS Code plugin
• Atom plugin
• Grunt plugin
• Gulp plugin

License

MIT

Changelog

3.0.0 (December 13, 2021)

• Added custom reporters support in CLI, e.g. csstree-validator --reporter path/to/reporter.js or csstree-validator --reporter reporter-package
• Added Symbol.iterator for validateString(), validateDictionary(), validateFile(), validatePathList() and validatePath() result value, i.e. it now can be used with for ... of for example for (const [filename, errors] of result) ...
• Bumped csstree to 2.0
• Package
  • Changed supported versions of Node.js to ^12.20.0, ^14.13.0 and >=15.0.0
  • Converted to ES modules. However, CommonJS is supported as well (dual module)
  • Added bundle dist/csstree-validator.esm.js as ES module